Dependencies

For your application to use the tree API, you need to import infinispan-tree.jar which can be located in the Infinispan binary distributions, or you can simply add a dependency to this module in your pom.xml:

<dependencies>
  ...
  <dependency>
    <groupId>org.infinispan</groupId>
    <artifactId>infinispan-tree</artifactId>
    <version>$put-infinispan-version-here</version>
  </dependency>
  ...
</dependencies>

Creating a Tree Cache

The first step to use the tree API is to actually create a tree cache. To do so, you need to create an Infinispan Cache as you'd normally do, and using the TreeCacheFactory, create an instance of TreeCache. A very important note to remember here is that the Cache instance passed to the factory must be configured with invocation batching. For example:

import org.infinispan.config.Configuration;
import org.infinispan.tree.TreeCacheFactory;
import org.infinispan.tree.TreeCache;
...
Configuration config = new Configuration();
config.setInvocationBatchingEnabled(true);
Cache cache = new DefaultCacheManager(config).getCache();
TreeCache treeCache = TreeCacheFactory.createTreeCache(cache);

Manipulating data in a Tree Cache

The Tree API effectively provides two ways to interact with the data:

1. Via TreeCache convenience methods: These methods are located within the TreeCache interface and enable users to store, retrieve, move, remove...etc data with a single call that takes the Fqn, in String or Fqn format, and the data involved in the call. For example:

   treeCache.put("/persons/john", "surname", "Smith");

   Or:

   import org.infinispan.tree.Fqn;
   ...
   Fqn johnFqn = Fqn.fromString("persons/john");
   Calendar calendar = Calendar.getInstance();
   calendar.set(1980, 5, 2);
   treeCache.put(johnFqn, "birthdate", calendar.getTime()));

2. Via Node API: It allows finer control over the individual nodes that form the FQN, allowing manipulation of nodes relative to a particular node. For example:

   import org.infinispan.tree.Node;
   ...
   TreeCache treeCache = ...
   Fqn johnFqn = Fqn.fromElements("persons", "john"); 
   Node<String, Object> john = treeCache.getRoot().addChild(johnFqn);
   john.put("surname", "Smith");

   Or:

   Node persons = treeCache.getRoot().addChild(Fqn.fromString("persons"));
   Node<String, Object> john = persons.addChild(Fqn.fromString("john"));
   john.put("surname", "Smith");

   Or even:

   Fqn personsFqn = Fqn.fromString("persons");
   Fqn johnFqn = Fqn.fromRelative(personsFqn, Fqn.fromString("john"));
   Node<String, Object> john = treeCache.getRoot().addChild(johnFqn);
   john.put("surname", "Smith");

   A node also provides the ability to access its parent or children. For example:

   Node<String, Object> john = ...
   Node persons = john.getParent();

   Or:

   Set<Node<String, Object>> personsChildren = persons.getChildren();

Common Operations

In the previous section, some of the most used operations, such as addition and retrieval, have been shown. However, there are other important operations that are worth mentioning, such as remove:

You can for example remove an entire node, i.e. /persons/john , using:

treeCache.removeNode("/persons/john");

Or remove a child node, i.e. persons that a child of root, via:

treeCache.getRoot().removeChild(Fqn.fromString("persons"));

You can also remove a particular key/value pair in a node:

Node john = treeCache.getRoot().getChild(Fqn.fromElements("persons", "john"));
john.remove("surname");

Or you can remove all data in a node with:

Node john = treeCache.getRoot().getChild(Fqn.fromElements("persons", "john"));
john.clearData();

Another important operation supported by Tree API is the ability to move nodes around in the tree. Imagine we have a node called "john" which is located under root node. The following example is going to show how to we can move "john" node to be under "persons" node:

Current tree structure:

   /persons
   /john

Moving trees from one FQN to another:

Node john = treeCache.getRoot().addChild(Fqn.fromString("john"));
Node persons = treeCache.getRoot().getChild(Fqn.fromString("persons"));
treeCache.move(john.getFqn(), persons.getFqn());

Final tree structure:

   /persons/john